home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / Python 1.4 / ic / ic-documentation.txt next >
Encoding:
Text File  |  1997-01-10  |  4.8 KB  |  108 lines  |  [TEXT/R*ch]
  1. Standard Module `ic'
  2. ====================
  3.  
  4. This module provides access to macintosh Internet Config package, which
  5. stores preferences for Internet programs such as mail address, default
  6. homepage, etc. Also, Internet Config contains an elaborate set of
  7. mappings from Macintosh creator/type codes to foreign filename
  8. extensions plus information on how to transfer files (binary, ascii,
  9. etc).
  10.  
  11. There is a low-level companion module `icglue' which provides the basic
  12. ic access functionality. This low-level module is not documented, but
  13. the docstrings of the routines document the parameters and the routine
  14. names are the same as for the Pascal or C API to Internet Config, so
  15. the standard IC programmers documentation can be used if this module is
  16. needed.
  17.  
  18. The `ic' module defines the `error' exception and symbolic names for
  19. all error codes IC can produce, see the source for details.
  20.  
  21. The `ic' module defines the following functions:
  22.  
  23.  - function of module ic: IC ([SIGNATURE, IC])
  24.      Create an internet config object. The signature is a 4-char creator
  25.      code of the current application (default `'Pyth'') which may
  26.      influence some of ICs settings. The optional IC argument is a
  27.      low-level `icinstance' created beforehand, this may be useful if
  28.      you want to get preferences from a different config file, etc.
  29.  
  30.  - function of module ic: launchurl (URL [, HINT])
  31.  
  32.  - function of module ic: parseurl (DATA [, START, END, HINT])
  33.  
  34.  - function of module ic: mapfile (FILE)
  35.  
  36.  - function of module ic: maptypecreator (TYPE, CREATOR [, FILENAME])
  37.  
  38.  - function of module ic: settypecreator (FILE)
  39.      These functions are "shortcuts" to the methods of the same name,
  40.      described below.
  41.  
  42.  
  43. IC objects
  44. ----------
  45.  
  46. IC objects have a mapping interface, hence to obtain the mail address
  47. you simply get `ic['MailAddress']'. Assignment also works, and changes
  48. the option in the configuration file.
  49.  
  50. The module knows about various datatypes, and converts the internal IC
  51. representation to a "logical" python datastructure. Running the `ic'
  52. module standalone will run a test program that lists all keys and
  53. values in your IC database, this will have to server as documentation.
  54.  
  55. If the module does not know how to represent the data it returns an
  56. instance of the ICOPAQUEDATA type, with the raw data in its DATA
  57. attribute. Objects of this type are also acceptable values for
  58. assignment.
  59.  
  60. Besides the dictionary interface IC objects have the following methods:
  61.  
  62.  - Method on IC object: launchurl (URL [, HINT])
  63.      Parse the given URL, lauch the correct application and pass it the
  64.      URL. The optional HINT can be a scheme name such as `mailto:', in
  65.      which case incomplete URLs are completed with this scheme
  66.      (otherwise incomplete URLs are invalid).
  67.  
  68.  - Method on IC object: parseurl (DATA [, START, END, HINT])
  69.      Find an URL somewhere in DATA and return start position, end
  70.      position and the URL. The optional START and END can be used to
  71.      limit the search, so for instance if a user clicks in a long
  72.      textfield you can pass the whole textfield and the click-position
  73.      in START and this routine will return the whole URL in which the
  74.      user clicked. HINT is again an optional scheme used to complete
  75.      incomplete URLs.
  76.  
  77.  - Method on IC object: mapfile (FILE)
  78.      Return the mapping entry for the given FILE, which can be passed
  79.      as either a filename or an FSSPEC object, and which need not exist.
  80.  
  81.      The mapping entry is returned as a tuple `(version, type, creator,
  82.      postcreator, flags, extension, appname, postappname, mimetype,
  83.      entryname)', where VERSION is the entry version number, TYPE is
  84.      the 4-char filetype, CREATOR is the 4-char creator type,
  85.      POSTCREATOR is the 4-char creator code of an optional application
  86.      to post-process the file after downloading, FLAGS are various bits
  87.      specifying whether to transfer in binary or ascii and such,
  88.      EXTENSION is the filename extension for this file type, APPNAME is
  89.      the printable name of the application to which this file belongs,
  90.      POSTAPPNAME is the name of the postprocessing application,
  91.      MIMETYPE is the MIME type of this file and ENTRYNAME is the name
  92.      of this entry.
  93.  
  94.  - Method on IC object: maptypecreator (TYPE, CREATOR [, FILENAME])
  95.      Return the mapping entry for files with given 4-char TYPE and
  96.      CREATOR codes. The optional FILENAME may be specified to further
  97.      help finding the correct entry (if the creator code is `'????'',
  98.      for instance).
  99.  
  100.      The mapping entry is returned in the same format as for MAPFILE.
  101.  
  102.  - Method on IC object: settypecreator (FILE)
  103.      Given an existing FILE, specified either as a filename or as an
  104.      FSSPEC record, set its creator and type correctly based on its
  105.      extension. The finder is told about the change, so the finder icon
  106.      will be updated quickly.
  107.  
  108.